@std/esm

@std/esm

This fast, small, zero-dependency package is all you need to enable ES modules in Node 4+ today!

See the release post :book: and video :movie_camera: for all the details.

Getting started

1. Run npm i --save @std/esm in your app or package directory.

2. Create the ESM loader to import your main ES module:

   index.js

   require = require("@std/esm")(module)
   module.exports = require("./main.mjs").default
   

By default, @std/esm only processes files of packages that opt-in with a @std/esm options object or @std/esm as a dependency, dev dependency, or peer dependency in their package.json. However, you can enable processing all files with specific options by passing an options object as the second argument or passing true to use the options from your package.json.

require = require("@std/esm")(module, options)

Enable ESM in the Node CLI with the -r option:

node -r @std/esm file.mjs

Enable ESM in the Node REPL:

node -r @std/esm

Or upon entering:

$ node
> require("@std/esm")
@std/esm enabled
> import p from "path"
undefined
> p.join("hello", "world")
'hello/world'

Note: The "cjs" and "gz" options are unlocked in the Node REPL.

Standard Features

The @std/esm loader is as spec-compliant as possible and follows Node’s ESM rules.

:point_right: This means, by default, ESM requires the use of the .mjs file extension.
:unlock: You can unlock ESM with the .js file extension using the "js" ESM mode.

Out of the box @std/esm just works, no configuration necessary, and supports:

• import / export
• import.meta
• Dynamic import()
• Improved errors
• Live bindings
• Loading .mjs files as ESM
• The file URI scheme
• Node 4+ support

Unlockables

Unlock extra features with "@std/esm":options or "@std":{"esm":options} in your package.json.

Commonly used options may be specified in shorthand form:

• "@std/esm":"js" is shorthand for "@std/esm":{"esm":"js"}
• "@std/esm":"cjs" is shorthand for "@std/esm":{"cjs":true,"esm":"js"}

{ "@std/esm": {
"esm":	A string ESM mode: "mjs" files as ESM (default) "all" files as ESM "js" and other files with import, export, or "use module" as ESM
"cjs":	A boolean to unlock CJS features in ESM.
"await":	A boolean to support top-level await in the main ES module.
"gz":	A boolean to support gzipped module (i.e. .js.gz, .mjs.gz). Note: Don’t forget the webpack gzip-loader.
} }

Cont’d

The "cjs" option may also be specified as an object.

{ "@std/esm": { "cjs": {
"cache":	A boolean for storing ES modules in require.cache.
"extensions":	A boolean for respecting require.extensions in ESM.
"interop":	A boolean for __esModule interoperability.
"namedExports":	A boolean to support importing named exports of CJS modules.
"paths":	A boolean for following CJS path rules in ESM.
"topLevelReturn":	A boolean to support top-level return.
"vars":	A boolean to expose __dirname, __filename, and require in ESM.
} } }

DevOpts

{ "@std/esm": {
"cache":	A boolean for toggling .cache creation (default: true).
"debug":	A boolean for unmasking stack traces.
"sourceMap":	A boolean for including inline source maps. Note: Automatically enabled using the Node CLI --inspect option.
"warnings":	A boolean for logging parse and runtime warnings. (default: process.env.NODE_ENV !== "production")
} }

Tips

• Load @std/esm before @babel/register v7+
• Load @std/esm with the “require” option of ava, mocha, nyc, and tape
• Load @std/esm with the --node-arg=-r --node-arg=@std/esm option of node-tap
• Use options "@std/esm":"cjs" or "@std/esm":{"cjs":{"cache":true}} with the Mocha --watch option
• Use options "@std/esm":"cjs" with webpack
• When in doubt, use options "@std/esm":"cjs"